---

Inside Macintosh: Imaging with QuickDraw

Previous | Chapter Top | Chapter Contents | Next |

GWorldPtr

An offscreen graphics world in Color QuickDraw contains a CGrafPort record--and its handles to associated PixMap and ColorTable records--that describes an offscreen graphics port and contains references to a GDevice record and other state information. The actual data structure for an offscreen graphics world is kept private to allow for future extensions. However, when your application uses the NewGWorld function to create an offscreen world, NewGWorld returns a pointer of type GWorldPtr by which your application refers to the offscreen graphics world. This pointer is defined as follows:

TYPE GWorldPtr = CGrafPtr;


On computers lacking Color QuickDraw, GWorldPtr points to an extension of the GrafPort record.

GWorldFlags

Several routines in this chapter expect or return values defined by the GWorldFlags data type, which is defined as follows:

TYPE GWorldFlags =
SET OF (
    pixPurge,               {specify to NewGWorld to make base address }
                            { for offscreen pixel image purgeable}
    noNewDevice,            {specify to NewGWorld to not create a new }
                            { GDevice record for offscreen world}
Note: QuickTime 3 for Windows does not support the noNewDevice flag.

    useTempMem,             {specify to NewGWorld to create base }
                            { address for offscreen pixel image in }
                            { temporary memory}
    keepLocal,              {specify to NewGWorld to keep offscreen }
                            { pixel image in main memory}
    gWorldFlag4,            {reserved}
    gWorldFlag5,            {reserved}
    pixelsPurgeable,        {returned by GetPixelsState to indicate }
                            { that base address for offscreen pixel }
                            { image is purgeable; specify to }
                            { SetPixelsState to make base address for }
                            { pixel image purgeable}
    pixelsLocked,           {returned by GetPixelsState to indicate }
                            { that base address for offscreen pixel }
                            { image is locked; specify to }
                            { SetPixelsState to lock base address for }
                            { offscreen pixel image}
    gWorldFlag8,            {reserved}
    gWorldFlag9,            {reserved}
    gWorldFlag10,           {reserved}
    gWorldFlag11,           {reserved}
    gWorldFlag12,           {reserved}
    gWorldFlag13,           {reserved}
    gWorldFlag14,           {reserved}
    gWorldFlag15,           {reserved}
    mapPix,                 {returned by UpdateGWorld if it remapped }
                            { colors to a new color table}
    newDepth,               {returned by UpdateGWorld if it translated }
                            { pixel map to a different pixel depth}
    alignPix,               {returned by UpdateGWorld if it realigned }
                            { pixel image to onscreen window}
    newRowBytes,            {returned by UpdateGWorld if it changed }
                            { rowBytes field of PixMap record}
    reallocPix,             {returned by UpdateGWorld if it reallocated }
                            { base address for offscreen pixel image}
    gWorldFlag21,           {reserved}
    gWorldFlag22,           {reserved}
    gWorldFlag23,           {reserved}
    gWorldFlag24,           {reserved}
    gWorldFlag25,           {reserved}
    gWorldFlag26,           {reserved}
    gWorldFlag27,           {reserved}
    clipPix,                {specify to UpdateGWorld to update and clip }
                            { pixel image}
    stretchPix,             {specify to UpdateGWorld to update and }
                            { stretch or shrink pixel image}
    ditherPix,              {specify to UpdateGWorld to dither pixel }
                            { image}
    gwFlagErr,              {returned by UpdateGWorld if it failed}
);


pixPurge

If you specify this flag for the flags parameter of the NewGWorld function, NewGWorld (described on NewGWorld ) makes the base address for the offscreen pixel image purgeable.

noNewDevice

If you specify this flag for the flags parameter of the NewGWorld function, NewGWorld does not create a new offscreen GDevice record; instead, NewGWorld uses either the GDevice record you specify or the GDevice record for a video card on the user's system.

Note: QuickTime 3 for Windows does not support the noNewDevice flag.

useTempMem

If you specify this in the flags parameter of the NewGWorld function, NewGWorld creates the base address for an offscreen pixel image in temporary memory. You generally should not use this flag. You should use temporary memory only for fleeting purposes and only with the AllowPurgePixels procedure (described on AllowPurgePixels ) so that other applications can launch.

keepLocal

If you specify this in the flags parameter of the NewGWorld function, NewGWorld creates a pixel image in Macintosh main memory where it cannot be cached to a graphics accelerator card.

gWorldFlag4

Reserved.

gWorldFlag5

Reserved.

pixelsPurgeable

If you specify this in the state parameter of the SetPixelsState procedure (described on SetPixelsState ), SetPixelsState makes the base address for an offscreen pixel map purgeable. If you use the  SetPixelsState procedure without passing it this flag, then SetPixelsState makes the base address for an offscreen pixel map unpurgeable. If the GetPixelsState function (described on GetPixelsState ) returns this flag, then the base address for an offscreen pixel is purgeable.

pixelsLocked

If you specify this flag for the state parameter of the SetPixelsState procedure, SetPixelsState locks the base address for an offscreen pixel image. If you use the SetPixelsState procedure without passing it this flag, then  SetPixelsState unlocks the offscreen pixel image. If the GetPixelsState function returns this flag, then the base address for an offscreen pixel is locked.

gWorldFlag8

Reserved.

gWorldFlag9

Reserved.

gWorldFlag10

Reserved.

gWorldFlag11

Reserved.

gWorldFlag12

Reserved.

gWorldFlag13

Reserved.

gWorldFlag14

Reserved.

gWorldFlag15

Reserved.

mapPix

If the UpdateGWorld function (described on UpdateGWorld ) returns this flag, then it remapped the colors in the offscreen pixel map to a new color table.

newDepth

If the UpdateGWorld function returns this flag, then it translated the offscreen pixel map to a different pixel depth.

alignPix

If the UpdateGWorld function returns this flag, then it realigned the offscreen pixel image to an onscreen window.

newRowBytes

If the UpdateGWorld function returns this flag, then it changed the rowBytes field of the PixMap record for the offscreen graphics world.

reallocPix

If the UpdateGWorld function returns this flag, then it reallocated the base address for the offscreen pixel image. Your application should then reconstruct the pixel image or draw directly in a window instead of preparing the image in an offscreen graphics world.

gWorldFlag21

Reserved.

gWorldFlag22

Reserved.

gWorldFlag23

Reserved.

gWorldFlag24

Reserved.

gWorldFlag25

Reserved.

gWorldFlag26

Reserved.

gWorldFlag27

Reserved.

clipPix

If the UpdateGWorld function returns this flag, then it clipped the pixel image.

stretchPix

If the UpdateGWorld function returns this flag, then it stretched or shrank the offscreen image.

ditherPix

If the UpdateGWorld function returns this flag, then it dithered the offscreen image.

gwFlagErr

If the UpdateGWorld function returns this flag, then it was unsuccessful and the offscreen graphics world was left unchanged.